home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1994 March / Internet Info CD-ROM (Walnut Creek) (March 1994).iso / networking / ip / ka9q / xobbs.arc / docs.xo next >
Text File  |  1989-05-03  |  9KB  |  216 lines
  1.           DOCUMENTATION FOR VERSION 1.3 OF W2XO BBS
  2.  
  3.  
  4. The W2XO PBBS for use with KA9Q's NET tcp/ip networking program
  5. is written for Unix SysV systems to allow multi-user PBBS service
  6. to the AX25 community. As it is a normal Unix executable file,
  7. the PBBS may also be accessed by telephone modem or locally on any
  8. terminal of the system.
  9.  
  10. Local Invocation of the PBBS is done by typing "xobbs <call>" at
  11. a system prompt.
  12.  
  13. In the AX25 support mode, the PBBS is spawned by NET, using a
  14. modified version of ax25cmd.c, ax25subr.c and ax25.c. 
  15. Input to and output from the PBBS are routed to and from NET via
  16. System V Message queues. NET passes the user's call to the PBBS
  17. for log-in purposes. 
  18.  
  19. There are four Sys V IPC message queues used for Communication
  20. between NET and XOBBS. All data going to NET for output is
  21. sent on the 'smsgqid'. All incoming data is received by the
  22. XOBBS from 'net' on the 'rsmgqid'. There are also two control
  23. message queues called 'rcmsgqid' and 'scmsgqid' which are used
  24. to exchange control and syncronization messages. Steering of
  25. the messages from and several concurrent XOBBS instances is
  26. done by using the process ID of the bbs to which the message
  27. is addressed as the IPC message type. Messages from a bbs to
  28. 'net' are sent with the bbs process id as a message type also,
  29. so that 'net' knows from whence they came. Sys V IPC allows
  30. selective receiving of messages from the queue by type.
  31. The first two queues are basically ascii text to and from
  32. the BBS and NET. The messages on the second(control) set of
  33. queues consists of 'kill me' messages (K) to NET from the bbs
  34. when the user disconnects or the forwarder is done, or 'go to
  35. next forwarding session' , etc when forwarding PBBS mail.
  36.  
  37.  
  38. HOMEDIR 
  39.  
  40.     The home directory of the bbs should be entered in
  41. The makefile. Change the definition to that of the directory in
  42. which you wish to run the bbs.
  43.  
  44.  
  45. CONFIGURATION FILE
  46.  
  47. Somewhat similarly to the WA7MBL and W0RLI ms-dos PBBS programs,
  48. XOBBS has a configuration file. CONFIG.XO contains the names
  49. of the directories and files used by the PBBS, allowing some
  50. flexibility of configuration. This file will be expanded in
  51. the future to allow various prompts, timeouts, etc.
  52.  
  53.  
  54. MULTI-USER MAIL SCHEME
  55.  
  56. The PBBS uses a "mail header" file which duplicates the first line of
  57. the message file. Each message is wholly self-contained in its own file.
  58. Messages are originally written to a directory specified as
  59. "tempdir" in the CONFIG.XO file. A mail daemon process, MAILDAEMON.C
  60. is awakened by any new message filed or old message deleted from
  61. the TEMPDIR, by user signal 16, on which it is sleeping. MAILDAEMON
  62. scans TEMPDIR and takes appropriate action based on the TOCALL
  63. and ATBBS fields in the message header and the contents of the
  64. file 'dist' the directory 'fwding'. If the message is addressed to
  65. some other ATBBS than W2XO (or none), then first the DIST file
  66. is scanned for a match between the ATBBS field and a mailing
  67. distribution list name. If a match occurs, then a copy of the
  68. message is filed in MAILDIR and given the next message number
  69. in sequence as the filename. Links are then made to the
  70. message file to files in the FWDING directory which contain
  71. the call letters of the PBBS to which distribution is to be made
  72. followed by unique characters (a concatenation of process number in
  73. ascii and message instance). These files are used to trigger the
  74. reverse forwarding and forwarding mechanisms.
  75.     I suggest running 'maildaemon' from an endless loop in a shell
  76. script, so that if anything causes it to crash, it will be
  77. re-spawned. This hasn't happened lately, but used to do so with
  78. some regularity.
  79.  
  80. FORWARDING FILE
  81.     This is ALMOST the same as the RLI/MBL style forwarding files.
  82. The major changes are the elimination of "via" or "v" ahead of the
  83. digipeater names in the connect message and only "G" lines are accepted,
  84. not "F" lines. ALSO, DIGIPEATERS are allowed only on G lines for now.
  85.     If you don't have RLI or MBL documentation handy, a skeleton
  86. outline is:
  87.     File "segments" begin at the file beginning of after "*** EOF"
  88. and continue to the next "*** EOF".
  89.     Each segment may contail CC, S ,R , and G lines as well as the
  90.       call letters of all stations/bbses reachable via the path
  91.       which is established in this segment.
  92.     A "CC" line sends a connect request to NET if in the forwarding mode.
  93.     A "S" line is transmitted verbatim over the ax25 link.
  94.     An "R" line is compared with the next line received over the
  95.     ax25 link and an error is returned if there is no match.
  96.     A "G" line gives the call letters of the bbs or node to which to
  97.     connect. After the G is A-E, signifying the device on which the
  98.         connection is to be attempted, ax0 thru ax4 (A is ax0, B is
  99.         ax1 and so on). The "G" line also contains the time window for
  100.         forwarding to each bbs. This is not used in this version
  101.         because it is assumed that the user will create a CRON script
  102.         to initiate forwarding.
  103.     Lines containing the call letters of all bbses/stations served by
  104.     this connection can follow the "G" line up to the next "*** EOF".
  105.  
  106.   EXAMPLE:
  107.     
  108. CC PGH03
  109. SC KA3JSD v WB3JSI
  110. RPGH03:WA3YOA-3> Connected to KA3JSD
  111. GA0023C KA3JSD
  112. WA3TVG
  113. KA3JSD
  114. NE3E
  115. WB3AMR
  116. *** EOF
  117.     
  118.     These lines mean, in the same order:
  119.  
  120.     send "C PGH03" to NET, which connects to the netrom node (PGH03).
  121.     send "C KA3JSD v WB3JSI" out the link to the net rom node(PGH03).
  122.     check reply from node as: "PGH03:WA3YOA-3> Connected to KA3JSD"
  123.     connection is on port A (ax0) and is to KA3JSD
  124.     WA3TVG,KA3JSD,NE3E and WB3AMR's mail go to this bbs.
  125.     *** EOF is the end of the segment.
  126.  
  127.  
  128. INITIATING FORWARDING
  129.     To initiate forwarding, run the process "trigger". This will
  130.     send a forwarding request up the message queue to 'net', causing
  131.         spawing of a bbs which will attempt to deliver all unsent messages
  132.     in the FWDING directory by initiating ax25 connections to the proper
  133.         bbses as defined in the forwarding file "fwd.xo". Be sure trigger
  134.     is owned by the proper user ID.
  135.     
  136. REVERSE FORWARDING
  137.     When the bbs receives the "SID" from a system which has initiated
  138.         a connect to the bbs ([RLI-Ver6.2-$] or some such), it returns
  139.         its own SID and the two then agree that reverse forwarding is
  140.         possible. At the end of the incoming mail session, the remote
  141.         bbs will transmit "F>", which will cause the XOBBS to scan its
  142.         files/directories for mail to the remote bbs and deliver it.
  143.  
  144. PARAMETER FILE
  145.  
  146. A parameter file which contains both the next message number to
  147. be assigned and the number of active messages is specified in
  148. CONFIG.XO by PARAMFIL. It is read a log-in and by MAILDAEMON
  149. to assign message numbers.
  150.  
  151. USER PERMISSIONS,ETC
  152.  
  153.     I run XOBBS and NET under a pseudo-user name of "net". XOBBS has its
  154. setuid bit set so that no matter who runs it, the files created are owned
  155. by "net". NET is started up under the same user name. All files and directories
  156. used are owned by "net". The programs 'maildaemon', 'trigger' and
  157. 'makhdrfil' are also owned by 'net' with setuid bit on.
  158.  
  159. HELP FILES
  160.  
  161.     The help system consists of files with the extent '.hlp'. Put
  162. these in HOMEDIR.
  163.  
  164. IN CASE OF TROUBLE
  165.     Check:
  166.         File protections
  167.         setuid bit on xobbs, maildaemon, makdhrfil and trigger.
  168.         config file(make sure it corresponds to what you really have)
  169.         device assignments in "startup.net".
  170.         if you get a file creation error message, create the file
  171.             yourself by copying /dev/null to it.
  172.  
  173.  
  174. SIGNAL USAGE
  175.  
  176.    Signal Name   number      origin(mode)          purpose
  177.  
  178.     SIGUSR1  signal 16   xobbs(rec)     fires up maildaemon
  179.  
  180. MESSAGE QUE USAGE
  181.  
  182. rmsgqid  receive message que...messages TO the bbs FROM net
  183. smsgqid  send message que...messages FROM the bbs TO net
  184. crmsgqid control messages TO the bbs FROM net (currently not used)
  185. csmsgqid control messages FROM the bbs TO net.
  186.  
  187.  
  188. CONTROL MESSAGE FORMAT
  189.  
  190. K       where xxxx is an ascii bbs pid.... Kill bbs with that pid .
  191. N    message FROM forwarder bbs process "go to next bbs in file".
  192. F    message from 'trigger' to 'net'.."Spawn the forwarder". 
  193.  
  194. EXAMPLE DIRECTORY STRUCTURE
  195.  
  196.                       /U/NEWBBS
  197.       -------------------------------------------------------------
  198.       mail(dir)  temp(dir)  fwding(dir) dist  fwd.xo   (help files)  
  199.     I        I        I
  200.  (mail messages) (new msgs)  (to-be-fwd)
  201.  
  202.  
  203. HEADER FILE
  204.  
  205. The header file will grow until the program 'makhdrfil' is run,
  206. which will write out a new header file and clean out any garbage.
  207. I suggest a 'crontab' entry to run 'makhdrfil' in the wee hours.
  208. If it is run while the bbs is heavily loaded, it may cause
  209. some confusion, with a station logging on during the process of
  210. re-writing the file getting only part of the header file. This
  211. will not effect bbs operation, except that that user will not
  212. be able to list all the messages.
  213.  
  214. Good Luck    -Jim
  215.  
  216.